Service Provider Configuration

Configuring a Service Provider

To configure an application as a PicketLink Service Provider you need to follow this steps:

Configuring the web.xml.
Configure an Authenticator.
Configure a Security Domain for your application.
Configure PicketLink JBoss Module as a dependency.
Create and configure a file named WEB-INF/picketlink.xml.

Configuring the web.xml

Before configuring your application as an Service Provider you need to add some configurations to your web.xml.

Let's start by defining a security-constraint element to restrict access to resources from unauthenticated users:

<security-constraint> 
    <web-resource-collection> 
        <web-resource-name>Manager command</web-resource-name> 
        <url-pattern>/*</url-pattern> 
    </web-resource-collection> 
    <auth-constraint> 
        <role-name>manager</role-name> 
    </auth-constraint> 
</security-constraint>

<security-role>
    <description>
      The role that is required to log in to the Manager Application
    </description>
    <role-name>manager</role-name>
</security-role>

As you can see above, we define that only users with a role named manager are allowed to access the protected resources. Make sure to give your users the same role you defined here, otherwise they will get a 403 HTTP status code.

During the logout process, PicketLink will try to redirect the user to a logout.jsp page located at the root directory of your application. Please, make sure to create it.

Please, make sure you have a welcome file page in your application. You can define it in your web.xml or simply create an index.jsp at the root directory of your application.

The picketlink.xml configuration file

All the configuration for an especific Service Providers goes at the WEB-INF/picketlink.xml file. This file is responsible to define the behaviour of the Authenticator. During the service provider startup, the authenticator parses this file and configures itself.

Bellow is how the picketlink.xml file should looks like:

<PicketLink xmlns="urn:picketlink:identity-federation:config:2.1">


    <PicketLinkSP xmlns="urn:picketlink:identity-federation:config:2.1"
        BindingType="REDIRECT"
        RelayState="someURL"
        ErrorPage="/someerror.jsp"
        LogOutPage="/customLogout.jsp"
        IDPUsesPostBinding="true"
        SupportsSignatures="true">

        <IdentityURL>http://localhost:8080/idp/ </IdentityURL>
        <ServiceURL>http://localhost:8080/employee/ </ServiceURL>

        <KeyProvider ClassName="org.picketlink.identity.federation.core.impl.KeyStoreKeyManager">

            <Auth Key="KeyStoreURL" Value="/jbid_test_keystore.jks" />
            <Auth Key="KeyStorePass" Value="store123" />
            <Auth Key="SigningKeyPass" Value="test123" />
            <Auth Key="SigningKeyAlias" Value="servercert" />

            <ValidatingAlias Key="localhost" Value="servercert" />
            <ValidatingAlias Key="127.0.0.1" Value="servercert" />

        </KeyProvider>

    </PicketLinkSP>

    <Handlers xmlns="urn:picketlink:identity-federation:handler:config:2.1">

        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2IssuerTrustHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2LogOutHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.SAML2AuthenticationHandler" />
        <Handler class="org.picketlink.identity.federation.web.handlers.saml2.RolesGenerationHandler" />

     </Handlers>

</PicketLink>

The schema for the picketlink.xml file is available here: https://github.com/picketlink/federation/blob/master/picketlink-core/src/main/resources/schema/config/picketlink_v2.1.xsd.

PicketLinkSP Element

This element defines the basic configuration for the service provider. The table bellow provides more information about the attributes supported by this element:

Name	Description	Value
EntityID	Defines the entity ID for this provider, as defined by the specs.	Usually an URI. No default value.
BindingType	Defines which SAML binding should be used: SAML HTTP POST or Redirect bindings.	POST\|REDIRECT. Defaults to POST if not specified.
ErrorPage	Defines a custom error page to be displayed when some error occurs during the request processing.	Defaults to /error.jsp.
LogOutPage	Defines a custom logout page to be displayed after the logout.	Defaults to /logout.jsp.
IDPUsesPostBinding	Indicates if the Identity Provider configured for this Service Provider is always using POST for SAML responses.	true\|false. Defaults to true if not specified.
SupportsSignature	Indicates if digital signature/verification of SAML assertions are enabled. If this attribute is marked to true the Identity Provider configured for this Service Provider must support signatures too, otherwise the SAML messages will be considered as invalid.	true\|false. Defaults to false if not specified.
LogOutUrl	An URL that will be used to send logout requests to the IdP. If not specified, defaults to the URL specified in the IdentityURL.	Defaults to IdentityURL, if not specified.
LogOutResponseLocation	An URL that will be used to send logout responses to the IdP. If not specified, defaults to the issuer of the incoming logout request.	Defaults to the issuer of the logout request.

IdentityURL Element

This element value refers to the URL of the Identity Provider used by this Service Provider.

Eg.: http://localhost:8080/idp/

ServiceURL Element

This element value refers to the URL of the Service Provider.

Eg.: http://localhost:8080/sales/

SAML Digital Signature Configuration (KeyProvider Element)

To enable digital signatures for the SAML assertions you need to configure:

Set the SupportsSignature attribute to true;
Add the SAML2SignatureGenerationHandler and the SAML2SignatureValidationHandler in the handlers chain (Handler Element).
Configure a KeyProvider* *element.

SAML Handlers Configuration (Handlers Element)

PicketLink provides some built-in Handlers to help the Service Provider Authenticator processing the SAML requests and responses.

The handlers are configured through the Handlers element.